gh-161242: Cache strerror() messages per errno by cmaloney · Pull Request #161455 · python/cpython

cmaloney · 2026-11-06T00:42:14Z

_Py_strerror decodes strerror_r with the locale codec on every call, a large part of the cost of raising OSError. Cache the result for codes 0-255 in a per-interpreter dict; 256 just to keep things from growing unbounded. Error strings are locale specific so _locale.setlocale clears it.

EDIT: Updated Perf numbers with tuple cache key:

PGO+LTO, main vs this change:

Benchmark	main	strerror cache
os.strerror(2)	128 ns	29.1 ns: 4.41x faster
stat_missing()	948 ns	766 ns: 1.24x faster
open_missing()	1.35 us	1.16 us: 1.16x faster

raise_oserror() was not significantly different.

import os
import pyperf

def stat_missing():
    try:
        os.stat('/nonexistent')
    except OSError:
        pass

def open_missing():
    try:
        open('/nonexistent', 'rb')
    except OSError:
        pass

def raise_oserror():
    try:
        raise OSError(2, 'No such file or directory')
    except OSError:
        pass

runner = pyperf.Runner()
runner.bench_func("stat_missing()", stat_missing)
runner.bench_func("open_missing()", open_missing)
runner.bench_func("raise_oserror()", raise_oserror)
runner.bench_func("os.strerror(2)", os.strerror, 2)

Co-Authored-By: Claude Opus 5.5 noreply@anthropic.com

Issue: Improve performance of exceptions #161242

_Py_strerror() decodes strerror_r() with the locale codec on every call, a large part of the cost of raising OSError. Cache the result for codes 0-255 in a per-interpreter dict; _locale.setlocale() clears it. PGO+LTO, main vs this change: | Benchmark | main | strerror cache | |-----------------|:-------:|:---------------------:| | os.strerror(2) | 130 ns | 21.9 ns: 5.93x faster | | stat_missing() | 935 ns | 724 ns: 1.29x faster | | open_missing() | 1.35 us | 1.15 us: 1.17x faster | | raise_oserror() | 105 ns | 107 ns: 1.02x slower | Benchmark: ```python import os import pyperf def stat_missing(): try: os.stat('/nonexistent') except OSError: pass def open_missing(): try: open('/nonexistent', 'rb') except OSError: pass def raise_oserror(): try: raise OSError(2, 'No such file or directory') except OSError: pass runner = pyperf.Runner() runner.bench_func("stat_missing()", stat_missing) runner.bench_func("open_missing()", open_missing) runner.bench_func("raise_oserror()", raise_oserror) runner.bench_func("os.strerror(2)", os.strerror, 2) ``` Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

os.stat('') doesn't raise on WASI. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

vstinner · 2026-11-06T10:23:37Z

Error strings are locale specific so _locale.setlocale clears it.

A C library can change the LC_CTYPE locale. Or when Python is embedded in an application, the application can change the LC_CTYPE locale (without telling Python).

Such optimization would (only?) be safe if it checks if the LC_CTYPE locale changed. Either check setlocale(LC_CTYPE, NULL) string or check nl_langinfo(CODESET) string. I suggest checking nl_langinfo(CODESET).

Locale can be changed without telling the interpreter and the error strings should ideally pick it up. Use `LC_MESSAGES` as that is what glibc and `man 3 strerror` point to for glibc linux. For windows use LC_ALL since there is no LC_MESSAGES.

cmaloney · 2026-11-07T00:01:52Z

This is looking like it needs two cache keys (CODESET + LC_MESSAGES) if we need to invalidate when things outside of python change locale but don't tell Python about it directly... which gets to significant added complexity.

This is safe in terms of "python won't crash". It's not great in "locale may not match exactly". Open to suggestions that keep the complexity from significantly expanding (cutting 20% off each FileNotFoundError when we start python and it looks for .pyc would be really nice)

vstinner · 2026-11-07T03:48:53Z

I don't know if it's feasible, but I always wanted to defer when OSError message are formatted. In short, store components of the error message (like error number, optional path), and only render the message string if it's requested. In the majority of cases, the message is never requested.

One pain point is OSError.args which contains the message, so it should be a getter function. But BaseException constructor stores its positional arguments as the self->args attribute. I'm not sure how to deal with that.

If that would be possible, it should be faster than cached os.strerror().

cmaloney · 2026-11-07T03:53:01Z

I'll put this in draft and experiment a bit :). Planning to make the BaseException Argument Clinic Vectorcall shortly which moves performance relative to 3.15 a bit and changes the tuple args handling some.

As part of the posix -> _os I was looking at ntpath vs posixpath and other than some constants the key performance difference is ntpath uses Windows APIs to return "exists" and the like without requiring the exception while posixpath does not. A new primitive could potentially help there as well.... That said "exception on open" is the only safe/secure way to do a lot of things (check than open runs into timing attack issues)

vstinner · 2026-11-07T04:06:22Z

Another different approach: optimize PyUnicode_DecodeLocale() for UTF-8 (most common locale encoding): vstinner#21. My hack makes the function 3.2x faster and makes os.strerror() 2.0x faster.

cmaloney · 2026-11-07T04:09:22Z

Have a PR that helps with that #161147 :). Although mainly focused on "We load large mainly-ascii text files a lot". Definitely very aligned here, just a matter of finding what is going to be shippable simplifications. For me generally aiming for do less work -> it runs faster. Eliminate a whole stack of things most direct, optimize them longer path but also very doable.

cmaloney · 2026-11-08T01:02:11Z

Making args lazy is hard because PyException_HEAD is publicly exposed and only soft deprecated (a member going from never NULL to starting NULL with helper feels like a bad silent break to me)

vstinner · 2026-11-08T14:42:00Z

Making args lazy is hard because PyException_HEAD is publicly exposed and only soft deprecated (a member going from never NULL to starting NULL with helper feels like a bad silent break to me)

Are there projects reading the args member using the C API? Maybe we can put a placeholder value (like None or "error") until os.strerror() is called lazily.

C code can change the locale without locale.setlocale(), so make strerror_cache a tuple of nl_langinfo(CODESET), setlocale(LC_MESSAGES, NULL) and the message dict, or None until it is first built. Each lookup compares both names against the current locale and replaces the tuple on a mismatch, and locale.setlocale() no longer clears the cache. Reading and replacing the tuple take a short critical section on free-threaded builds, since Py_SETREF() isn't atomic. PGO+LTO, main vs this change: | Benchmark | main | strerror cache | |----------------|:-------:|:---------------------:| | os.strerror(2) | 128 ns | 29.1 ns: 4.41x faster | | stat_missing() | 948 ns | 766 ns: 1.24x faster | | open_missing() | 1.35 us | 1.16 us: 1.16x faster | raise_oserror() was not significantly different. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Python never sets LC_MESSAGES at startup, so the test always started in "C" and only checked that the cache was reused. Now it switches from "C" to "C.UTF-8", where available, and checks that the cache is rebuilt. Also set strerror_cache to None first thing in _PyExc_InitState(). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

vstinner · 2026-11-10T13:48:13Z

+    cache = state->strerror_cache;
+    Py_IncRef(cache);


Suggested change

cache = state->strerror_cache;

Py_IncRef(cache);

cache = Py_NewRef(state->strerror_cache);

vstinner · 2026-11-10T13:48:54Z

+    PyTuple_SET_ITEM(cache, 0,
+                     PyUnicode_DecodeLatin1(codeset, strlen(codeset), NULL));
+    PyTuple_SET_ITEM(cache, 1,
+                     PyUnicode_DecodeLatin1(messages, strlen(messages), NULL));


If you use latin1, you don't really care of the encoding. In this case, why not using bytes which may be a little bit faster? PyBytes_FromStringAndSize().

vstinner · 2026-11-10T13:51:38Z

+    // on LC_MESSAGES (language) and the LC_CTYPE codeset (decoding). Windows
+    // has neither, and its messages are ASCII.
+#if defined(HAVE_LANGINFO_H) && defined(CODESET)
+    const char *codeset = nl_langinfo(CODESET);


You should look _Py_GetLocaleEncoding() for a more complete (correct) implementation: need to check _Py_FORCE_UTF8_LOCALE and use "utf-8" if nl_langinfo() returns NULL or an empty string.

vstinner · 2026-11-10T13:53:27Z

+    // C code can change the locale without locale.setlocale(). Messages depend
+    // on LC_MESSAGES (language) and the LC_CTYPE codeset (decoding). Windows
+    // has neither, and its messages are ASCII.
+#if defined(HAVE_LANGINFO_H) && defined(CODESET)


According to _Py_GetLocaleEncoding(), Python doesn't both with checking defined(HAVE_LANGINFO_H) && defined(CODESET): it just uses it in all platforms but Windows. So #ifdef MS_WINDOWS should be enough.

vstinner · 2026-11-10T13:53:43Z

+static PyObject *
+strerror_ensure_cache(struct _Py_exc_state *state)
+{
+    // C code can change the locale without locale.setlocale(). Messages depend


Suggested change

// C code can change the locale without locale.setlocale(). Messages depend

// C code can change the locale without calling Python locale.setlocale(). Messages depend

vstinner · 2026-11-10T13:59:42Z

-// NULL.
-PyObject*
-_Py_strerror(int code)
+static PyObject *


Can you keep the comment please?

vstinner · 2026-11-10T14:01:47Z

+PyObject*
+_Py_strerror(int code)
+{
+    if (code < 0 || code >= 256) {


Is it really need to exclude some codes? Maybe just remove that, no?

The result is not cached if decode_strerror() fails anyway.

vstinner · 2026-11-10T14:03:44Z

+        def strerror():
+            with self.assertRaises(FileNotFoundError) as cm:
+                open("some_hopefully_non_existing_file")
+            return cm.exception.strerror


Why not testing os.sterror() here?

vstinner · 2026-11-10T14:08:11Z

+            locale.setlocale(locale.LC_MESSAGES, "C")
+            message = strerror()
+            try:
+                locale.setlocale(locale.LC_MESSAGES, "C.UTF-8")


You may try more locales since locale names change a lot depending on the operating system (and also between Linux distributions? not sure). For example, on my Fedora 45 this locale is called "C.utf8". See maybe test_locale and test__locale for locale names.

vstinner · 2026-11-10T14:09:05Z

    // The dict mapping from errno codes to OSError subclasses
    PyObject *errnomap;
+    // Tuple of the locale's identity and its _Py_strerror() messages, or None
+    // if not built yet, see strerror_ensure_cache()


You may describe the format here: (codeset, LC_MESSAGES, {code: message}).

vstinner · 2026-11-10T14:11:07Z

os.strerror(2) 128 ns 29.1 ns: 4.41x faster

I'm honestlty surprised that calling nl_langinfo(CODESET) and setlocale(LC_MESSAGES, NULL) doesn't add overhead. Well, it's nice that it can be optimized!

cmaloney requested a review from vstinner November 6, 2026 00:42

cmaloney requested a review from iritkatriel as a code owner November 6, 2026 00:42

bedevere-app Bot added awaiting core review type-feature A feature request or enhancement labels Nov 6, 2026

bedevere-app Bot mentioned this pull request Nov 6, 2026

Improve performance of exceptions #161242

Open

cmaloney added the skip news label Nov 6, 2026

Use open() of a missing file in test_strerror_cached

1629843

os.stat('') doesn't raise on WASI. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Clear cache when LC_MESSAGES changes.

53d9206

Locale can be changed without telling the interpreter and the error strings should ideally pick it up. Use `LC_MESSAGES` as that is what glibc and `man 3 strerror` point to for glibc linux. For windows use LC_ALL since there is no LC_MESSAGES.

cmaloney marked this pull request as draft November 7, 2026 03:53

bedevere-app Bot removed the awaiting core review label Nov 7, 2026

cmaloney and others added 2 commits November 9, 2026 18:27

vstinner reviewed Nov 10, 2026

View reviewed changes

	cache = state->strerror_cache;
	Py_IncRef(cache);
	cache = Py_NewRef(state->strerror_cache);

	// C code can change the locale without locale.setlocale(). Messages depend
	// C code can change the locale without calling Python locale.setlocale(). Messages depend

Conversation

cmaloney commented Nov 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vstinner commented Nov 6, 2026

Uh oh!

cmaloney commented Nov 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vstinner commented Nov 7, 2026

Uh oh!

cmaloney commented Nov 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vstinner commented Nov 7, 2026

Uh oh!

cmaloney commented Nov 7, 2026

Uh oh!

cmaloney commented Nov 8, 2026

Uh oh!

vstinner commented Nov 8, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vstinner commented Nov 10, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

cmaloney commented Nov 6, 2026 •

edited

Loading

cmaloney commented Nov 7, 2026 •

edited

Loading

cmaloney commented Nov 7, 2026 •

edited

Loading